Code Quality, Formatting and Linter

Java Coding standard

https://www.oracle.com/technetwork/java/codeconventions-150003.pdf

Java standard naming conventions

https://www.javaguides.net/2018/08/java-standard-naming-conventions.html

Best Practices for Designing RESTful APIs

1. Use Nouns for Resource Identification The fundamental concept of a REST-based system is the resource. A resource is anything you want to expose to the outside world through your application.

Example 1: Resources for an Employee Management System:

Employee
Department
Projects
Task
Address

Example 2: Resources for a Student Management System:

Student
Teacher
School
Class
Subject

It is best practice to use nouns for resource identification.

For easy understanding, use this structure for every resource:

GET - /users - Returns a list of users
GET - /users/100 - Returns a specific user
POST - /users - Create a new user
PUT - /users/100 - Updates a specific user
DELETE - /users/711 - Deletes a specific user

2. Use Plural Nouns to Name a Resource When developing a resource in a REST API, use plural nouns. Consistency is key.

Examples:

Use /students instead of /student
Use /employees instead of /employee
Use /orders instead of /order
Use /users instead of /user
Use /customers instead of /customer

3. Use Proper HTTP Headers for Serialization Formats Both client and server need to know which format is used for communication. The format must be specified in the HTTP header.

Content-Type: Defines the request format. Accept: Defines a list of acceptable response formats. Example:

Content-Type: application/json
Accept: application/json

4. GET Method and Query Parameters Should Not Alter the State To alter the state, use the PUT, POST, and DELETE methods instead of GET. Do not use GET for state changes.

Examples:

Incorrect: GET /users/711?activate
Correct: POST /users/711/activate

5. Use Sub-Resources for Relations If a relation can only exist within another resource, model it as a sub-resource.

Pattern for Sub-Resources:

GET /{resource}/{resource-id}/{sub-resource}
GET /{resource}/{resource-id}/{sub-resource}/{sub-resource-id}
POST /{resource}/{resource-id}/{sub-resource}

Example:

GET /cars/711/drivers/ - Returns a list of drivers for car 711
GET /cars/711/drivers/4 - Returns driver #4 for car 711

6. Use Proper HTTP Methods (Verbs) Using the right HTTP methods ensures clarity and adheres to REST principles.

Examples:

GET: Retrieve data.

GET /api/books - Retrieve a list of books. POST: Create a new resource.

POST /api/books - Add a new book. PUT: Update an existing resource or create it if it doesn't exist.

PUT /api/books/123 - Update details of a specific book with ID 123. PATCH: Apply partial modifications to a resource.

PATCH /api/books/123 - Update the title of a specific book with ID 123. DELETE: Remove a specific resource.

DELETE /api/books/123 - Delete a book with ID 123.

7. HTTP Response Status Codes When the client raises a request to the server through an API, the client should know the feedback. HTTP status codes provide standardized responses for various scenarios. The server should always return the right status code.

Common Status Codes:

200 OK: The request is successful. 201 Created: A new resource is created. 400 Bad Request: The server failed to process the request due to malformed syntax. 401 Unauthorized: Authentication is required. 403 Forbidden: The server refuses to respond to the request. 404 Not Found: The requested resource is not found. 500 Internal Server Error: An unexpected error occurred on the server.

8. Field Name Casing Convention Follow a consistent casing convention across the application. For JSON, use camelCase.

Example:

{
  "firstName": "Ramesh",
  "lastName": "Fadatare",
  "id": 100,
  "userName": "Ramesh Fadatare",
  "email": "ramesh@gmail.com"
}

9. Searching, Sorting, Filtering, and Pagination Support these operations in the existing GET REST API by appending query parameters.

Examples:

Sorting: GET /companies?sort=rank_asc
Filtering: GET /companies?category=banking&location=india
Searching: GET /companies?search=Digital
Pagination: GET /companies?page=23

10. RESTful API Versioning API versioning is the practice of managing changes to your API transparently. Common methods include:

Versioning through URI Path Versioning through query parameters Versioning through custom headers Versioning through content negotiation Example:

http://www.example.com/api/v1/products http://www.example.com/api/v2/products

Real-World Use Case: E-commerce Platform API Let's apply these best practices to design an API for an e-commerce platform that manages products, categories, and orders.

Resources
Product

GET /api/products - Returns a list of products
GET /api/products/{id} - Returns a specific product
POST /api/products - Creates a new product
PUT /api/products/{id} - Updates a specific product
DELETE /api/products/{id} - Deletes a specific product
Category

GET /api/categories - Returns a list of categories
GET /api/categories/{id} - Returns a specific category
POST /api/categories - Creates a new category
PUT /api/categories/{id} - Updates a specific category
DELETE /api/categories/{id} - Deletes a specific category
Order

GET /api/orders - Returns a list of orders
GET /api/orders/{id} - Returns a specific order
POST /api/orders - Creates a new order
PUT /api/orders/{id} - Updates a specific order
DELETE /api/orders/{id} - Deletes a specific order

Use of Plural Nouns All resources are named using plural nouns, ensuring consistency and clarity.

HTTP Headers for Serialization The API supports JSON format for requests and responses.

Example:

Content-Type: application/json Accept: application/json Query Parameters for Searching, Sorting, Filtering, and Pagination Sorting Products:

GET /api/products?sort=price_asc - Sorts products by price in ascending order. Filtering Products:

GET /api/products?category=electronics&availability=true - Filters products that belong to the electronics category and are available. Searching Products:

GET /api/products?search=laptop - Searches for products with the keyword "laptop." Pagination:

GET /api/products?page=2&limit=20 - Retrieves the second page of products, with 20 products per page. Versioning The API uses URI Path versioning to manage different versions of the API.

Example:

http://www.example.com/api/v1/products http://www.example.com/api/v2/products

Code Formatting and Linter

Below steps to be followed in order to incorporate spotless plugin to format your code in an uniform way across the application. Include the below mentioned changes in your build.gradle file in your local setup as a mandatory step.

Note: This needs to be included in all repositories in your local workspace except init-containers. This is one of the action items to handle the code quality w.r.t formatting. Request you to go through this steps and implement in your local setup.

Step 1: Include id 'com.diffplug.spotless' version '6.25.0' under plugins

Step 2: Below block of code to be placed in your respective local environment repository ‘build.gradle’ file.

spotless {

	ratchetFrom 'feature/kafkasetup'
	
	java {

		target project.fileTree(dir: 'src', include: '**/*.java')

		importOrder()
		removeUnusedImports()
		cleanthat()
		googleJavaFormat().aosp()
		formatAnnotations()
		indentWithSpaces()
		trimTrailingWhitespace()
		endWithNewline()

	}
}

ratchetFrom : This option supports with the files changed after this will be formatted. Value

'feature/kafkasetup' : This is the branch name from which we have done our local setup. Spotless will identify the formatting related observations with newly changed files on this branch while running the gradle build.

Step 3: Open the Terminal window to execute further step

Step 4: Execute below commands will build the project. Terminal id 'com.diffplug.spotless' version '6.25.0' under plugins

To build the project – this will throw errors if any w.r.t spotless findings in recent modified code. .\gradlew build

To build the project with auto correction of fixes identified by spotless – build will be successful. .\gradlew build:spotlessApply

Ensure – Before raising PR [code commit operation], newly added/modified codes were applied with spotless fix by executing .\gradlew build:spotlessApply Please note, spotlessApply will not be part of central pipeline because it will change the code format at runtime which is not expected, Hence all the spotless fixes should be applied in local development environment with testing before raising PR.